USA Driver's License Verification API

This document highlights the details of the USA Driver's License Verification API.

API Description

Objective

The USA Driver's License Verification API checks the information on an individual's Driver's license (DL) or ID card and confirms if it matches the official data maintained by the American Association of Motor Vehicle Administrators (AAMVA).

Info

Driver's licenses, driving permits, and ID cards issued by U.S. jurisdictions are commonly used for identity verification, but these documents can sometimes be counterfeit or altered. Therefore, it is crucial for organizations to verify their authenticity to ensure accurate identification.

Input	Output
The individual's details including: First name Last name Driver's license number State Date of birth Address Details	The verification results indicating whether the driver's license holder's data matches the official records, including respective match statuses for each input field

AAMVA Database

The American Association of Motor Vehicle Administrators (AAMVA) maintains a system that facilitates secure, electronic exchange of identity information between member jurisdictions for driver's licenses and state IDs.
Currently, the AAMVA database covers 43 out of 50 states. For the remaining seven states not covered by the AAMVA database.
The seven states not covered by the AAMVA database are: Alaska (AK), California (CA), Louisiana (LA), Minnesota (MN), New York (NY), Pennsylvania (PA), Utah (UT). If the driver's license under verification belongs to one of these seven states, additional address details (address, ZIP code, and city name) are required for verification.

API URL

https://usa.thomas.hyperverge.co/v1/dlVerification

API Endpoint

dlVerification

Overview

The USA Driver's License Verification API is RESTful and uses standard HTTP verbs and status codes. The requests are in form-data format and responses are in JSON format.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
transactionId	Optional	The unique ID for the customer journey	Not Applicable

Inputs

The following table lists the parameters required for the USA Driver's License Verification API's request body:

Parameter	Mandatory or Optional	Type	Description	Input Format	Default Value
`firstName`	Mandatory	string	The first name of the driver's license holder	Not Applicable	Not Applicable
`lastName`	Mandatory	string	The last name of the driver's license holder	Not Applicable	Not Applicable
`dlNumber`	Mandatory	string	The Driver's license number of the driver's license holder	Not Applicable	Not Applicable
`state`	Mandatory	string	The state where the Driver's license was issued	The state code of the respective state in the DL. For example, TX for Texas.	Not Applicable
`dob`	Mandatory	string	The date of birth of the driver's license holder	The date of birth should be in DD-MM-YYYY format	Not Applicable
`address`	Conditionally Mandatory	string	The residential address of the driver's license holder. Required for states not covered by the AAMVA Database	Not Applicable	Not Applicable
`zip`	Conditionally Mandatory	string	The ZIP code associated with the residential address of the driver's license holder. Required for states not covered by the AAMVA Database	The standard five-digit ZIP code	Not Applicable
`city`	Conditionally Mandatory	string	The city name associated with the residential address of the driver's license holder. Required for states not covered by the AAMVA Database	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the USA Driver's License Verification API:

curl --location --request POST 'https://usa.thomas.hyperverge.co/v1/dlVerification' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--data '{
    "firstName": "<Enter_first_name>",
    "lastName": "<Enter_last_name>",
    "state": "<Enter_state>",
    "dlNumber": "<Enter_DL_number>",
    "dob": "<Enter_date_of_birth>",
    // The following fields are optional and are only required when searching for states not covered by the AAMVA database.
    "address": "<Enter_the_Address>", 
    "zip": "<Enter_the_ZIP_Code>", 
    "city": "<Enter_the_City_Name>" 
}'

Success Response

The following code snippet demonstrates a success response from the USA Driver's License Verification API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "dlNumberMatch": true,
            "firstNameMatch": true,
            "lastNameMatch": true,
            "dobMatch": true,
            "stateMatch": true
        },
        "summary": {
            "action": "pass",
            "details": []
        }
    }
}

Success Response Details

The following table outlines the details of the success response from the Driver's License Verification API:

Parameter	Type	Description
status	string	The status of the API request
statusCode	integer	The HTTP status code indicating the result of the request
result	object	The result object containing verification details
result.details	object	Verification results for the driver's license information
result.details.dlNumberMatch	boolean	Indicates if the driver's license number matches
result.details.firstNameMatch	boolean	Indicates if the first name matches
result.details.lastNameMatch	boolean	Indicates if the last name matches
result.details.dobMatch	boolean	Indicates if the date of birth matches
result.details.stateMatch	boolean	Indicates if the state ID or state code matches
result.summary	object	Summary of the verification action and details
result.summary.action	string	The action taken based on the verification results
result.summary.details	array	Additional details related to the verification, if any

Error Responses

The following are the error responses for the USA Driver's License Verification API:

Input Validation Error- Missing Fields
Missing/Invalid State Code
Input Validation Error- Incorrect Format of DoB
Input Validation Error- Missing DL Number
Missing/Invalid Credentials

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "dlNumberMatch": true,
            "firstNameMatch": null,
            "lastNameMatch": null,
            "dobMatch": true,
            "stateMatch": true
        },
        "summary": {
            "action": "fail",
            "details": [
                {
                    "code": "012",
                    "message": "First name is not matching"
                },
                {
                    "code": "013",
                    "message": "Last name is not matching"
                }
            ]
        }
    }
}

{
    "status": "failure",
    "statusCode": "400",
    "error": "Required field State is invalid"
}

{
    "status": "failure",
    "statusCode": "400",
    "error": "\"dob\" must be in DD-MM-YYYY format"
}

{
    "status": "failure",
    "statusCode": "400",
    "error": "Required field DriverLicenseNumber is invalid"
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Error Response Details

A failure or error response from the API contains a failure status with a relevant status code and error message.

The following table lists all the error responses:

Status Code	Error Message	Error Description	Error Resolution
200	First/Last name is not matching	The provided first/last name or both of them, do not match the official records	Verify that the first name and last name match the official records
400	Required field State is invalid	The request does not contain a valid state code	Provide a valid state code in the request (e.g., TX for Texas)
400	"dob" must be in DD-MM-YYYY format	The provided Date of Birth is not in DD-MM-YYYY format	Format the date of birth as DD-MM-YYYY in the request
400	Required field DriverLicenseNumber is invalid	The request does not contain a valid driver's license number	Provide a valid driver's license number in the request
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values	Provide valid `appId` and `appKey` credentials in the request
500	Internal Server Error	There was an error with the server	Please check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

Method - POST​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​